<html>
<head>
<title>ECW -- ERDAS Compress Wavelets (.ecw)</title>
</head>

<body bgcolor="#ffffff">

<h1>ECW -- ERDAS Compress Wavelets (.ecw)</h1>

GDAL supports .ecw format for read access and write.  The current 
implementation reads any number of bands but returns only as eight bit
image data.  Coordinate system and georeferencing transformations are read,
but in some cases coordinate systems may not translate.<p>

Support for the ECW driver in GDAL is optional, and requires linking
in external ECW SDK libraries provided by Intergraph (previously ERDAS).<p>

In addition to ECW files, this driver also supports access to network
image services using the "ECWP" protocol.  Use the full ecwp:// url of 
the service as the dataset name.  When built with SDK 4.1 or newer it
is also possible to take advantage of 
<a href="http://trac.osgeo.org/gdal/wiki/rfc24_progressive_data_support">
RFC 24</a> style asynchronous access to ECWP services.<p>

Starting with GDAL 1.9.0, XMP metadata can be extracted from JPEG2000 files, and will be
stored as XML raw content in the xml:XMP metadata domain.<p>

<h2>ECW metadata domain / Georeferencing update</h2>

(Starting with GDAL 1.9.0)<p>

The PROJ, DATUM and UNITS found in the ECW header are
reported in the ECW metadata domain. They can also be set with the SetMetadataItem()
method, in order to update the header information of an existing ECW file,
opened in update mode, without modifying the imagery.<p>

The geotransform and projection can also be modified with the SetGeoTransform()
and SetProjection() methods. If the projection is set with SetProjection() and
the PROJ, DATUM or UNITS with SetMetadataItem(), the later values will override the values
built from the projection string.<p>

<h2>ECW Version 3 Files</h2>
(Starting with GDAL 1.10.0)<p>

ECW 5.x SDK provides amended file format which allows to store data statistics, histograms,
metadata, rpc metadata and supports UInt16 as band data type.

Currently not everything is implemented: 
<ul>

<li><B>Statistics and Histograms</B> - full implementation for writing and reading. No ECW_OEM_KEY neccessary.
<li><B>File Metadata</B> - read only support. Statistics will also be preserved/updated during CreateCopy.
<li><B>RPC Metadata</B> - supported by file format, not supported by driver. 
<li><B>Header Metadata</B> - written by SDK itself. Reported by gdalinfo. 
</ul>


<h3>File Metadata Keys: </h3>

<ul>
<li>FILE_METADATA_ACQUISITION_DATE
<li>FILE_METADATA_ACQUISITION_SENSOR_NAME
<li>FILE_METADATA_ADDRESS
<li>FILE_METADATA_AUTHOR
<li>FILE_METADATA_CLASSIFICATION
<li>FILE_METADATA_COMPANY - should be set to ECW_OEM_KEY
<li>FILE_METADATA_COMPRESSION_SOFTWARE - updated during recompression
<li>FILE_METADATA_COPYRIGHT
<li>FILE_METADATA_EMAIL
<li>FILE_METADATA_TELEPHONE
</ul>

<h3>Following Header Metadata will be reported: </h3>
<ul>
<li>CLOCKWISE_ROTATION_DEG
<li>COLORSPACE (reported for V2 files as well)
<li>COMPRESSION_DATE
<li>COMPRESSION_RATE_ACTUAL
<li>COMPRESSION_RATE_TARGET (reported for V2 files as well)
<li>VERSION (reported for V2 files as well)
</ul>

<h2>Creation Issues</h2>

The ECW 4.x SDK from ERDAS is only free for image decompression.  To 
compress images it is necessary to build with the read/write SDK and to 
provide an OEM licensing key at runtime which may be purchased from ERDAS.<p>

For those still using the ECW 3.3 SDK, images less than 500MB may be 
compressed for free, while larger images require licensing from ERDAS.  See
the licensing agreement and the LARGE_OK option.<p>

Files to be compressed into ECW format must also
be at least 128x128.  ECW currently only supports 8 bits per channel for 
ECW Version 2 files. ECW Version 3 files supports 16 bits per channel 
(as Uint16 data type). Please see Creation options to enable ECW V3 files writing <p>

When writing coordinate system information to ECW files, many less
common coordinate systems are not mapped properly.  If you know the 
ECW name for the coordinate system you can force it to be set at
creation time with the PROJ and DATUM creation options. <p>

Creation Options:<p>

<ul>

<li> <b>TARGET=percent</b>: Set the target size reduction as a percentage of 
the original.  If not provided defaults to 90% for greyscale images, and 95%
for RGB images.<p>

<li> <b>PROJ=name</b>: Name of the ECW projection string to use. 
Common examples are NUTM11, or GEODETIC.<p>

<li> <b>DATUM=name</b>: Name of the ECW datum string to use. 
Common examples are WGS84 or NAD83.<p>

<li> <b>UNITS=name</b>: (GDAL &gt;= 1.9.0) Name of the ECW projection units to use :
METERS (default) or FEET (us-foot).<p>

<li> <b>LARGE_OK=YES</b>: When built with the ECW 3.x SDK this option can be 
set to allow compressing files larger than 500MB.  It is the users 
responsibility to ensure that the licensing requirments for large file 
compression are being adhered to.<p>

<li> <b>ECW_ENCODE_KEY=key</b>: Provide the OEM encoding key purchased from 
Erdas which permits encoding images.  The key is is approximately 129 hex 
digits long.  It may also be provided globally as a configuration option.<p>

<li> <b>ECW_ENCODE_COMPANY=name</b>: Provide the name of the company ERDAS
issued the OEM encoding key (see ECW_ENCODE_KEY) to.  This must exactly match
the name used by ERDAS in issuing the OEM key.  It may also be provided 
globally as a configuration option.<p>

<li> <b>ECW_FORMAT_VERSION=2/3</b>: (GDAL &gt;= 1.10.0) When build with the ECW 5.x SDK this option can be set to  
allow ECW Version 3 files to be created. This would allow to write UInt16 data type
rasters (new feature of ECW Version 3 files) . Default is 2 which will write ECW Version 2 files.<p>

</ul>

ECW format does not support creation of overviews since the ECW format 
is already considered to be optimized for "arbitrary overviews". <P>

<h2> Configuration Options </h2>

The ERDAS ECW SDK supports a variety of 
<a href="http://trac.osgeo.org/gdal/wiki/ConfigOptions">runtime configuration 
options</a> to control various features.  Most of these are exposed as GDAL 
configuration options.  See the ECW SDK documentation for full details on the
meaning of these options. 

<ul>
<li> <b>ECW_CACHE_MAXMEM=bytes</b>: maximum bytes of RAM used for in-memory 
caching.  If not set, up to one quarter of physical RAM will be used by the 
SDK for in-memory caching.<p>

<li> <b>ECWP_CACHE_LOCATION=path</b>: Path to a directory to use for caching
ECWP results.  If unset ECWP caching will not be enabled.<p>

<li> <b>ECWP_CACHE_SIZE_MB=number_of_megabytes</b>: The maximum 
number of megabytes of space in the ECWP_CACHE_LOCATION to be used for 
caching ECWP results.<p>

<li> <b>ECWP_BLOCKING_TIME_MS</b>: time an ecwp:// blocking read will wait
before returning - default 10000 ms.<p>

<li> <b>ECWP_REFRESH_TIME_MS</b>: time delay between blocks arriving and the 
next refresh callback - default 10000 ms.  For the purposes of GDAL this is
the amount of time the driver will wait for more data on an ecwp connection 
for which the final result has not yet been returned.  If set small then 
RasterIO() requests will often produce low resolution results.<p>

<li> <b>ECW_TEXTURE_DITHER=TRUE/FALSE</b>: This may be set to FALSE to disable
dithering when decompressing ECW files.  Defaults to TRUE.<p>

<li> <b>ECW_FORCE_FILE_REOPEN=TRUE/FALSE</b>: This may be set to TRUE to 
force open a file handle for each file for each connection made.  Defaults to 
FALSE.<p>

<li> <b>ECW_CACHE_MAXOPEN=number</b>: The maximum number of files to keep 
open for ECW file handle caching.  Defaults to unlimited.<p>

<li> <b>ECW_RESILIENT_DECODING=TRUE/FALSE</b>: Controls whether the reader
should be forgiving of errors in a file, trying to return as much data as is
available.  Defaults to TRUE.  If set to FALSE an invalid file will result
in an error.<p>

<li> <b>ECW_ENCODE_KEY, ECW_ENCODE_COMPANY</b>: These values, as described
in the creation options, may also be set as configuration options. See above.
<p>

</ul>

<h2>See Also:</h2>

<ul>
<li> Implemented in <tt>gdal/frmts/ecw</tt>.

<li> ECW SDK available at <a href="http://geospatial.intergraph.com/products/other/ecw/ERDASECWJPEG2000SDK/Details.aspx">geospatial.intergraph.com</a>.

<li> <a href="http://trac.osgeo.org/gdal/wiki/ECW">GDAL ECW Build Hints</a>

</ul>

</body>
</html>
